home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / glib19.zip / MACRO19.DOC < prev    next >
Text File  |  1991-06-27  |  71KB  |  2,114 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                 GLIB Macro-Routines
  16.                        Copyright (C), InfoSoft 1987-1990, 1991
  17.  
  18.  
  19.              GLIB contains and premieres several more complex routines not
  20.      available in ANY other library collection whatever the price.  These
  21.      routines do more, much more, than the average call to simply save the
  22.      screen image or whatever.  These are more like complete programs in
  23.      themselves, yet they remain callable from QB (and in some cases 'C')
  24.      to perform a function, or set of functions.  For lack of a better
  25.      term, we are calling this type of callable routine a macro-routine
  26.      to differentiate them from simple calls or primitives available from
  27.      most other run of the mill library collections.
  28.  
  29.             In spite of the fact that these tend to be far more complex and
  30.      functional than a typical  sub program primitive, they tend  to remain
  31.      mainly assembler; they may have the look  or profile of a higher-level
  32.      BASIC routine,   but most  remain in high-speed assembler.   Only MFed
  33.      and FlexMenu are in BASIC.  
  34.  
  35.  
  36.                                GLib Macro Routines
  37.            A.  MFed      - A complete input handler for editing input or
  38.                            that supports MACROS
  39.            B.  Clock     - An installable and accurate time display.
  40.            C.  QCalc     - A complete, full featured calculator.
  41.            D.  FlexMenu  - All purpose, flexible menuing routine
  42.            E.  StatLine  - A set of status line control routines.
  43.            F.  DialogBox - A lightning fast way to perform short I/O
  44.                            functions with an end user.
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                      Copyright (C) InfoSoft 1986-1989, 1990
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                             A.    Macro Input Editor
  77.                      Copyright (C) InfoSoft, 1987 - 1990, 1991
  78.  
  79.  
  80.                I.       Introduction
  81.  
  82.              There are several, indeed many, text input handlers around now
  83.      you have now stumbled upon the  most functional of them all.  MFed  is
  84.      fully modular, requires  no event trapping  switch and is packed  with
  85.      features.     MFed was  designed to  be a  powerful all-purpose  input
  86.      control editor  suitable  for virtually  any  and all  keyboard  input
  87.      situation,  yet still  remain modular, self  contained and  requires a
  88.      minimum of overhead.  In short,  it provides for maximum functionality
  89.      with a minimum of set up, dependencies and overhead.
  90.  
  91.           MFed, which stands for Macro Field Editor, is modular: it can
  92.           be called from the main code of most any another  program very   
  93.           easily.     
  94.  
  95.           MFed is highly configuarable:  You can change  most any of the   
  96.           operating parameters with the change of a flag or two.
  97.  
  98.           MFed does not require the use of any event trapping switch, it   
  99.           identifies extended key codes on its own, like most any text
  100.           input routine should.
  101.  
  102.           Finally, MFed utilizes the awesome power  of macros.  This allows
  103.           the end user to save loads of keystrokes  even redefining them on
  104.           the fly if you choose!  Even  if you do not use macros in your   
  105.           application, MFed remains a highly useful and powerful text input
  106.           control module.
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.           
  127.  
  128.                      Copyright (C) InfoSoft 1986-1989, 1990
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.              II.           MFed Parameters, Syntax
  143.  
  144.                MFED uses several  switches and 2  arguments to control  the
  145.      flow and text input.  The formal or direct parameters are:
  146.  
  147.           Text$    - The text string to edit.
  148.           FSize    - An integer telling MFED the maximum length allowed for
  149.                      the TEXT$, the current text to be edited.
  150.           Macro$() - An array of strings for use  as macro assignments to  
  151.                      the ALT + Alpha keys
  152.  
  153.          You should understand  that you  can actually use  any names  that
  154.      suit you  in invoking  MFED. That  is, you  could use  ED$ instead  of
  155.      TEXT$, or  T$, or whatever  you want.  MFED  will operate just  as ex-
  156.      pected, as  long as  you pass them  in the  right order.   The correct
  157.      syntax is:
  158.  
  159.           MRetCode = MFed(text$, fsize%, Macro$())
  160.  
  161.          The importance of  FSize is that MFed  will not allow  input after
  162.      that maximum size  is reached, and maybe beep (bleep  actually).  MFed
  163.      does not change FSize on the  return, so be sure to reset it  for each
  164.      successive call.
  165.  
  166.  
  167.  
  168.  
  169.  
  170.                III.       Incorporating MFED to your code
  171.  
  172.  
  173.             MFed  works  off of  3  formal  arguments (covered  above)  and
  174.      several COMMON parameters shared with the main, calling program.  This
  175.      allows you  to share some  parameters with  MFed very  easily such  as
  176.      Foreground Color, upper casing etc.
  177.  
  178.             The  actual use  and  meaning of  these  common parameters  are
  179.      covered later, here we are explaining how  to set up for MFed to  work
  180.      in your program.  This is done  by simply including the following line
  181.      in the beginning of your main code:
  182.  
  183.           COMMON /MFedVars/ fg%, bg%, fgd%, bgd%, Alarm%, bad$, editted%,_
  184.                hatch%, Mac%, nums%, num$, upcase%, RngLo#, RngHi#
  185.  
  186.           It is important  that you list them  EXACTLY as shown, ie  in the
  187.      order  shown, WITH the  type declarations.   The first four  are fore-
  188.      ground and background colors and the rest are listed alphabetically.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                      Copyright (C) InfoSoft 1986-1989, 1990
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.              Note  that such  COMMON statements  must appear  in  your code
  208.      BEFORE any  executable statements.   If you are not  familiar with the
  209.      use of   COMMON it is  suggested that you  review this in the  QB man-
  210.      ual(s). Also  refer to  the MFedDemo  source for  proper set  up.   In
  211.      implementing the MFed variables, we have opted to make several of them
  212.      COMMON to allow MFed to read  and literally share these variables with
  213.      your main program and at the same  time, keeps you from having to pass
  214.      all of them as formal arguments to MFed. That is, intead of:
  215.  
  216.           MCode = MFed (t$, fsiz, Macro$(), fg, bg, fgd,  bgd, alarm,_     
  217.                         editted, nums, num$, upcase, URng#, LRng#)
  218.  
  219.           all we do is:
  220.  
  221.           MCode = MFed(t$, fsiz, Macro$())
  222.  
  223.          Additionally, a benefit of this is that the COMMON switches are
  224.      typically  used or reset  MUCH less often  in use than  say, the text$
  225.      would be; for  example, most likely  you would set the  color switches
  226.      once (fg,  fgd, bg and  bgd), but text$  gets changed at  almost every
  227.      call.
  228.  
  229.  
  230.  
  231.          The use of a blockname (/MFedVars/) prevents MFED from interfering
  232.      with  other COMMON  or  COMMON SHARED  variables,  more precisely,  it
  233.      allows  the USE of additional COMMON or  COMMMON SHARED variables.  To
  234.      name additional variables as COMMON declare them like this:
  235.  
  236.        DEFINT a-z
  237.  
  238.        COMMON SHARED /MFedVars/ fg%, bg%, fgd%, bgd%, Alarm%, bad$,_
  239.                      editted%, hatch%, Mac%, nums%, num$, upcase%,_
  240.                      RngLo#, RngHi#
  241.  
  242.        COMMON SHARED /newblock/ arg1, arg2, arg3      ' different block
  243.  
  244.        COMMON SHARED  a,_                             ' "blank" block of
  245.                       b,_                             '   COMMON variables
  246.                       c,_
  247.                       z
  248.  
  249.  
  250.      Note that /MFedvars/ need not carry the SHARED attribute, but the
  251.      use of a blockname allows MFED to share those variables that it needs
  252.      and ONLY those, ie a SIZE error is not encountered if you use other
  253.      COMMON variables.  This allows for maximum flexibility.
  254.  
  255.          Of the /MFedvars/  variables, only  EDITTED, a more  or less  aux-
  256.      iliary flag is ever altered by MFed.
  257.  
  258.  
  259.  
  260.                      Copyright (C) InfoSoft 1986-1989, 1990
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.                IV.              Internal Editing Keys
  274.  
  275.                Internally,  MFed does several  things to  provide a  set of
  276.      powerful, professional editting  functions to it's operation.   First,
  277.      lets look at the editting functions and keys recognized:
  278.  
  279.  
  280.        [Home]       Places cursor at start of text or field.
  281.        [End]        Places cursor at first blank at end of the text.
  282.  
  283.        [Ctrl-End]   Clear line from cursor to end of line.
  284.        [Ctrl-X]     Clear all text from current field.
  285.        [Ctrl-U]     Undoes current edit.  This does not restore the text to
  286.                     it's form in a disk text file, but restores the text to
  287.                     the form it was UPON ENTRY TO MFED.  It cannot know    
  288.                     what the text was or what form it was in PRIOR to  the 
  289.                     CALL.
  290.  
  291.        Arrow Keys   Move one character Right or Left.  MFED will not  allow
  292.                     the user to Cursor right into the hatched area if that
  293.                     means that more than 1 space trails the text.  That is,
  294.                     via the the right arrow, it will not allow more than 2
  295.                     consecutive spaces, as in "J. DOE  " or "J Q  Public".
  296.                     Multiple spaces can be achieved via the insert key
  297.                     or space however.
  298.  
  299.  
  300.        Ctrl-Arrow   Moves one word right or left
  301.             Keys
  302.  
  303.  
  304.        [Tab]        Moves over 5 spaces without disturbing text.
  305.  
  306.        [Back Tab]   Back up 5 spaces without disturbing text.
  307.  
  308.  
  309.        [Ins]         Insert works as expected, allowing text to be inserted
  310.                     at the cursor, and  changes the cursor to a block.  The
  311.                     Insert state is toggled off upon exiting MFed or       
  312.                     "finishing" the field or text.
  313.  
  314.  
  315.        [Del]        As expected, deletes characters right of the cursor.
  316.  
  317.  
  318.        [Alt-A]      Invokes macro tied to that key if your program is    
  319.         to [Alt-Z]        allowing Macros.
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                      Copyright (C) InfoSoft 1986-1989, 1990
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.                V.              MFed Return Codes - FCODE
  340.  
  341.         Another major feature of MFed is the returns code.  This  indicates
  342.      to you  what key  is pressed  to exit  the routine  and therefore  can
  343.      indicate other functions to be handled by your code.
  344.  
  345.           MFed Returns:
  346.                               Location error -   -1
  347.                                   Enter   -    0
  348.                   Up Arrow  -  1            Ctrl   PgUp     -   5
  349.                   Dn Arrow  -  2                   PgDn     -   6
  350.                      PgUp   -  3         (Return codes 7 and 8 not used)
  351.                      PgDn   -  4                 Escape     -   9
  352.  
  353.                             F1 - F10 returns 11 thru 20
  354.  
  355.          Note that shifted function  keys are not trapped or  returned, and
  356.      returns 7 and 8 are omitted to allow function keys to return intuitive
  357.      values.
  358.  
  359.          By  acting on  the return,  MFED  acts not  only as  a  text input
  360.      control module but also as a  virtual control center: your application
  361.      can respond to F1  with Help, F2 to search  for a string, F3 to  add a
  362.      record and so forth.
  363.  
  364.          The  return of  a -1  code indicates  that  you have  attempted to
  365.      execute  the  MFed editing  functions too  close  to the  edge  of the
  366.      screen.  For example, attempting to edit  a field of 8 past postion 72
  367.      on the screen will return this.  This simply precludes a runtime error
  368.      by exiting gracefully.
  369.  
  370.  
  371.  
  372.  
  373.  
  374.              VI.         Internal Handling, COMMON Parameters
  375.  
  376.           MFed does a few things internally on its own and a few others you
  377.      control and change throughout the course  of your program by resetting
  378.      the COMMON parameters.  If you are not familiar with SHARED parameters
  379.      you should refer  to your QB manual.   These are not  passed as formal
  380.      arguments inside the  parentheses when the  program is CALLed but  are
  381.      set in your main program.
  382.  
  383.          o  The ALARM parameter indicates whether sound is to be on or off.
  384.             The sound is more of a bleep than a beep.  If this switch is
  385.             set (non zero) it allows the bleep sound effect to sound at
  386.             various times:
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                      Copyright (C) InfoSoft 1986-1989, 1990
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.               - An attempt to cursor right when the string has reached
  406.                 FSize (maximum length).
  407.               - An attempt to enter an invalid character (an alpha
  408.                 character  when nums is ON).
  409.               - When an inserted character will cause the text to exceed
  410.                 the maximum length.
  411.               - Cursor left attempted left of first character position.
  412.               - If cursor right appends more than 1 successive blanks to
  413.                 the text.
  414.  
  415.             Regardless of the state of ALARM, MFed disregards any such     
  416.      illegal activities.   Alarm just adds an  error sound to the  process.
  417.      While the error sound has it's uses,  thre are times when it is  inap-
  418.      propriate, such as  in an office  bullpen setting where such  BLEEPING
  419.      would be annoying - here, clear the Alarm flag (Alarm = 0).
  420.  
  421.  
  422.          o  MFed also highlights the current text or data as well as       
  423.             providing the hatching.  When the editing is completed, and one
  424.             of the 15 FCODE keys are hit to exit the field (actually MFed
  425.             is exited, and control is returned to you), the highlighting is
  426.             turned off.  This color control is handled thru the use of 2
  427.             sets of color codes: FG, BG and FGD and BGD.  These must be
  428.             assigned valid BASIC color codes in the course of your main
  429.             code.  At the start, MFed uses the FGD, BGD (as in
  430.             ForeGround_Data and BackGround_Data) colors and upon exiting,
  431.             redisplays it in the FG, BG colors.  These only need to be set
  432.             once.
  433.  
  434.  
  435.          o  BAD$ allows you to define invalid characters.  One instance
  436.             where this is extremely handy is when the input will be written
  437.             to a sequential file and you want to preclude excess commas
  438.             from being written.  Defining BAD$ as "," would cause MFed to
  439.             reject commas from being input and sound the alarm (depending
  440.             on the state of ALARM).
  441.  
  442.  
  443.          o  EDITTED is treated as a flag to indicate that the text string
  444.             upon exiting MFed is different than it  was at the start of the
  445.             CALL to MFed.  This allows you to test to see if field in  a   
  446.             record has been altered.   MFed only sets it to 1 never to 0.  
  447.             Since MFed is just handling the input for different strings, it
  448.             never knows  when a set of fields equalling a full record is   
  449.             completed.  EDITTED is how MFed tells you that something has   
  450.             indeed been edited.  ( Based on this flag, you can include code
  451.             in  your application to flash a message that an EDIT is in     
  452.             process, as is done in MFED-DEMO.  It is also useful in       
  453.             precluding certain functions if an edited record is not  saved.
  454.             An example of this is shown in MFED-DEMO where  paging is      
  455.             disallowed if a record is edited and unsaved.)
  456.  
  457.  
  458.                      Copyright (C) InfoSoft 1986-1989, 1990
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.         o   HATCH allows you to redefine the hatching character.  Using the
  472.             value of FSize as the maximum length allowed, MFed provides
  473.             hatching  from the end of the actual text to that maximum      
  474.             length.  If a  string is longer than FSize upon entry to MFed, 
  475.             it is truncated to  the maximum length.  The default character 
  476.             for hatching is ASCII 176, but can be set to anything  you wish
  477.             the HATCH variable.  
  478.  
  479.  
  480.          o  MAC allows you to enable  or disable macro processing.  If set 
  481.             to 1, macros are enabled, and  pressing Alt+ 'A' to 'Z' invokes
  482.             the macro you or your application has assined to that key.   If
  483.             MAC  is cleared or set to 0, macros are not allowed and ALT    
  484.             keypresses are ignored.
  485.  
  486.  
  487.          o  RngHi# and RngLo# allow  for internal range checking of values.
  488.             If RngHi# does NOT equal RngLo#, then range checking will be in
  489.             effect.  In this state, if an exit key is pressed (Enter, Up   
  490.             Arrow etc) AND the value of the  string being editted is LESS  
  491.             than RngHi# AND  GREATER than RngLo#, then MFed will consider  
  492.             the string to be invalid  and ONLY exit if the exit key was    
  493.             [Esc]  (this allows a way out of MFed even with 'invalid'      
  494.             input).  If Alarm  is active, it will sound on such invalid    
  495.             values.
  496.  
  497.  
  498.          o  Input can be limited with the NUMS switch.  Originally intended
  499.             to allow numbers only, it restricts input to the characters in
  500.             num$.   For example, in a phone number entry the characters    
  501.             "()-"  may be allowable beyond 0-9, but in a dollar based entry
  502.             $ and "." may  be allowable.  So prior to invoking  MFed, NUM$ 
  503.             would be set to "1234567890()-" for phone numbers, or          
  504.             ".1234567890$" for the dollar based entry.   If NUMS is set (1)
  505.             and NUM$ is clear ( "" ) the default is "-123456789".
  506.             Obviously, this allows other limited inputs such as in gender
  507.             selections of M or F.  Here, set UPCASE to 1, NUMS to 1 and
  508.             NUM$ to "MF". 
  509.  
  510.  
  511.          o  Caps or uppercase input from  the keyboard can be forced on the
  512.             fly (ie without a separate call) via the UPCASE switch.  Set   
  513.             UPCASE to 1 or non zero for caps, 0 for to allow either lower
  514.             or upper  case.  When UpCase is set, it converts the input to  
  515.             Upper. 
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                      Copyright (C) InfoSoft 1986-1989, 1990
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.                VII.            Macro Processing
  538.  
  539.           MFed acts upon Alt-alpha keystrokes to insert the string
  540.      associated with that combination into the field being edited.  The
  541.      power of this comes in applications that require repetitive stings to
  542.      be typed (such as city names).  If your application requires that the
  543.      end user needs to type 'Shawnee Mission' or 'Overland Park' with any
  544.      sort of frequency,  you could assign then as macros to the [Alt-S] and
  545.      [Alt-O] respectively.  From  there on, those strings could  be entered
  546.      into the current field with a single shifted keystoke.
  547.  
  548.          For your end user's  added convenience, you can embed an  exit key
  549.      to the end  of a macro eliminating  that step too!   Specifically, you
  550.      could add CHR$(13) to either (or both/all) macros and after MFed fills
  551.      the field  with the  macro contents,  it exists  with FCode  0!   Only
  552.      [Enter] (CHR$(13)) is handled  this way and only  when insert is  OFF,
  553.      Macros are allowed (MAC = 1) and provided the macro size (LEN) is less
  554.      than or equal to FSiz.
  555.  
  556.           MFED's macro processing automagically recognizes and respects the
  557.      INSERT state.  That is, with INSERT OFF [Alt-S] overwrites whatever is
  558.      in the field with 'Shawnee Mission'; with INSERT ON, the string is
  559.      inserted at the current location as long as room permits.
  560.  
  561.           Macros are stored in a conventional string array.  These can be
  562.      hard coded in your application (eg Macro$(1) = "qwerty") or they can
  563.      be read from  a disk file.   Again, note that  you can name  the array
  564.      anything you wish so that a large application could alternately use
  565.      several macro arrays so that one could hold city names, another could
  566.      contain common account or reference numbers, another common zip codes
  567.      or area codes and so forth.
  568.  
  569.           The  Macro  string array  is a  simple  35 element  string array,
  570.      referenced as follows:
  571.      Elements 1 to 10 control the top alpha key macros: [Alt-Q] to [Alt-P]
  572.      Elements 15 to 23 control those tied to middle row: [Alt-A] to [Alt-L]
  573.      Elements 29 to 35 control the bottom row: [Alt-Z] to [Alt-M]
  574.  
  575.      Note that not all 35 elements are used, eg a string stored to
  576.      Macro$(11) cannot be invoked.
  577.  
  578.      A Macro array can be qucikly filled from a disk file as follows: 
  579.           FOR x = 1 to 10
  580.               LINE INPUT #FilNo, Macro$(x)
  581.           NEXT x
  582.           FOR x = 15 to 23
  583.               LINE INPUT #FilNo, Macro$(x)
  584.           NEXT x
  585.           FOR x = 29 to 35
  586.               LINE INPUT #FilNo, Macro$(x)
  587.           NEXT x
  588.           CLOSE #FilNo
  589.  
  590.                      Copyright (C) InfoSoft 1986-1989, 1990
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.           If you do not wish to use macro processing, there are two ways to
  604.      disallow it.  The simplest is to only dimension Macro$() to 1.  If the
  605.      macro array is less than 35, MFed assumes that you do not want to use
  606.      macros.  Since the array is passed explicitly, it must be dimensioned
  607.      to at least 1 even if you are not using macros so that an error is not
  608.      encountered.
  609.  
  610.           You can temporarily or selectively suspend macro processing by
  611.      setting MAC to 0.  This causes MFed to ignore the macro processing
  612.      code regardless of  any assignments to Macro$() and Alt-keypresses. If
  613.      the end user attempts to invoke a macro from a "blank" key, MFed emits
  614.      a short, quiet click so that touch and fast typists can be warned that
  615.      no macro was available.
  616.  
  617.  
  618.           Note that you  can arrange your code  to even edit macros  on the
  619.      fly. By assigning this function to  one of the function keys, all  you
  620.      need do is edit a temporary string and then place it in the array:
  621.  
  622.         CASE 13                            ' assume F3 =edit macro
  623.             CALL SaveScrn(2001)            ' Save the main MFed screen
  624.             CALL Windows(1, 1, 5, 25, 0, 0, 1, 78, "")
  625.             LOCATE 24, 20
  626.             PRINT "Press key of Macro to edit"   ' find out which one
  627.             DO
  628.                 m$ = inkey$
  629.             LOOP UNTIL m$ > ""
  630.  
  631.             MacToEdit = ConvertKey(m$)     ' write a function to check to
  632.                                            ' see if it is a valid macro key
  633.                                            ' return the scan code minus 15
  634.             ed$ = Macro$(MacToEdit)
  635.             Mac = 0                    ' turn off macros for now
  636.             MCode = MFed(ed$, x, Macro$()) ' edit macro
  637.             IF MCode = 0 THEN              ' update/save if Enter hit
  638.                 Macro$(MacToEdit) = ed$    ' update macro array
  639.             END IF
  640.  
  641.  
  642.           Likewise,  one of the  function keys could  be used  to allow the
  643.      user to signal to your application  to save the current macro list  to
  644.      disk and yet another could be used to request a new set be loaded from
  645.      disk.
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.                      Copyright (C) InfoSoft 1986-1989, 1990
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.                                B.      CLOCK
  670.                     Copyright (C) InfoSoft 1986 - 1990, 1991
  671.  
  672.  
  673.          I.    Introduction
  674.  
  675.          CLOCK allows your  program to  provide an ongoing  display of  the
  676.      time time WITHOUT the hassle, heartache or overhead of executing GOSUB
  677.      statements to print TIME$.
  678.  
  679.          CLOCK works much the same as a DOS level TSR, that is, it installs
  680.      itself in memory, latching onto to certain system interrupts to update
  681.      a display of the current time as needed.  The format of the display is
  682.      " hh:mm:ss ?m " (12 hour format), with a trailing am or pm label.
  683.  
  684.           The problem with most similar time  display programs quite simply
  685.      is  that they are  not accurate!   Over the  long haul, a  simple time
  686.      keeping process is most likely to lose about  .02 seconds each second.
  687.      This may sound trivial or insignificant, but  in a mere 5 minutes, the
  688.      time display can  be off as much as 2 or  3 seconds!!  If your program
  689.      is to run for hours  on end, after a few hours, the  time display will
  690.      simply be inaccurate to a wholly unacceptable degree.
  691.  
  692.           To rectify this,  CLOCK uses  a secondary internal  clock to  es-
  693.      timate the amount of time lost from 'True' system time and periodical-
  694.      ly jumps ahead a  second to adjust.  The CLOCK in  GLIB does not loose
  695.      an entire second  until over 8 hours  have passed!  During  that time,
  696.      CLOCK's time display consistently  remained within a constant .5  to 1
  697.      second of the actual system time returned by TIME$.  In fact, after 12
  698.      hours, CLOCK is incredibly still within 1 second!  Over extremely long
  699.      periods,  even  CLOCK will  eventually  vary  from true  time,  so for
  700.      applications that run continually, to adjust the time simply uninstall
  701.      and immediately re install CLOCK.  This will allow it to re-synch with
  702.      the system time for another 8 to 10 hours.
  703.  
  704.  
  705.  
  706.           Accuracy is only part  of the superiority of CLOCK.  The friendly
  707.      12 hour-based display with  the am/pm label provides a  positive, easy
  708.      to read display and the time display  is fully configurable: it can be
  709.      located or  'popped  up' any  where on  the screen  and  in any  color
  710.      attribute.  CLOCK will also emit a small, pleasant audible tone on the
  711.      hour and on the half hour (even this is configurable).
  712.  
  713.           Since  CLOCK  does  take  of  advantage of  TSR-like  programming
  714.      techniques, it is installed  rather than simply called, to  invoke it.
  715.      Likewise it MUST be uninstalled prior to your program termination.  It
  716.      is advised that you fully develop and write your program without CLOCK
  717.      installed and only when  it is fully debugged should you  add CLOCK to
  718.      your code.
  719.  
  720.  
  721.  
  722.                      Copyright (C) InfoSoft 1986-1989, 1990
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.          II.    Syntax
  736.  
  737.          The syntax to implementing CLOCK is very simple:
  738.  
  739.          CALL CLOCK(row, col, attr, Func)
  740.          row  - The CRT line to display the time display at.
  741.          col  - The CRT column to display it at.
  742.          attr - The color in attribute form to use in the display.
  743.          Func - CLOCK function to perform:
  744.                 0 = uninstall clock
  745.                 1 = normal installation
  746.                 2 = quiet installation (do not beep at half hour           
  747.                     intervals.)
  748.  
  749.  
  750.  
  751.           Since CLOCK uses TSR type programming techniques, it must be
  752.      uninstalled when you are done with it.  This cannot be understated:
  753.      CLOCK MUST BE UNINSTALLED BEFORE PROGRAM TERMINATION.
  754.  
  755.           This includes program crashes!  In  the event of a runtime  error
  756.      or crash, CLOCK must  be uninstalled before your application  exits to
  757.      DOS.   This means  if you  use ON  ERROR type error  traps, a  call to
  758.      uninstall CLOCK should be performed.  Since CLOCK takes over some very
  759.      key system interrupts,  it is not advised  that you use it  with other
  760.      TSR type programs or routines without a THOROUGH checking out of their
  761.      compatibility.
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.          III.   Programming Considerations
  770.  
  771.           CLOCK  cannot be  accidentally twice,  CLOCK checks  for  such an
  772.      attempt and precludes it.  Should you wish to change the attributes or
  773.      location of the display, perform two calls: the first to uninstall
  774.      CLOCK then another to reinstall it with the new color or location (or
  775.      both).  CLOCK does no internal display preservation, so should you do
  776.      an uninstall-install routine to change color or location, the last
  777.      image of the first clock installation will remain unless you restore
  778.      that portion of the screen or CLS or whatever.
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.                      Copyright (C) InfoSoft 1986-1989, 1990
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.                                   C.  QCalc
  802.                     Copyright (C) InfoSoft 1987 - 1990, 1991
  803.  
  804.  
  805.             I.      Introduction
  806.  
  807.           QCalc is one of the most  powerful and useful callable subroutine
  808.      in _any_ QB/BASCOM add on package.  QCALC has every feature found in a
  809.      cheap calculator, plus some.  QCalc handles values ranging from -2.147
  810.      to +2.147  BILLION in  either decimal  or fixed  point  (as in  dollar
  811.      values).
  812.  
  813.           Such a full featured routine is great in and of itself, but being
  814.      written entirely in assembler, QCalc takes _under_ 4k in your program!
  815.      QCalc is  completely self  sufficient: all  keyboard, video,  bios and
  816.      math calculations are _internal_  to it.  There are no dependencies on
  817.      other library routines you may or may not have available to you!
  818.  
  819.  
  820.            Any sort of bookkeeping or number based QB/BASCOM application
  821.      can  benefit greatly  from QCalc.   QCalc is  _not_ a TSR  but it does
  822.      remember the result from the last  invocation within the same applica-
  823.      tion!
  824.  
  825.  
  826.  
  827.             II.  Calculator Operation
  828.  
  829.           When first invoked, QCalc  will draw a representation of  a small
  830.      hand held calculator on the screen, complete with number keys and math
  831.      operators.    This true  to  life  representation makes  it  ideal for
  832.      accounting type systems where the user  or operator is not necessarily
  833.      a computer aficionado.
  834.  
  835.           QCalc invokes the Num-Lock key for even more convenience, and
  836.      as numbers are pressed,  the presses are replicated on  the calculator
  837.      display.   Remember, all  this  power is  available  to you  and  your
  838.      program with ONE simple CALL invocation.
  839.  
  840.           The default mode is Decimal Fixed Point entry since that is
  841.      the most likely method for adding sales, calculating tax etc.
  842.  
  843.  
  844.           Math Functions supported:
  845.           + ... Addition
  846.           - ... Subtraction
  847.           * ... Multiplication
  848.           / ... Division
  849.           = ... Equals (the Enter key also acts as an implicit equal sign).
  850.  
  851.  
  852.  
  853.  
  854.                      Copyright (C) InfoSoft 1986-1989, 1990
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.           Numeric Entry:
  868.           In Fixed Point  mode, the decimal can  be used to fix  the point.
  869.      That  is, entering 1 - 2 - 3 - 4 would result in a display of 1234.00,
  870.      however, 1 - 2 - . - 3 - 4 would result in 12.34.
  871.  
  872.           Commas are  not supported  as entry  characters in  decimal mode,
  873.      however they are displayed as needed.
  874.  
  875.  
  876.           Other Calculator Operations:
  877.  
  878.           [Alt -] \  Changes the sign of the entry (like the '+/-'
  879.           [Alt +] /  key on a calculator).  Note that these are
  880.                      the _top row_ plus and minus keys, not the
  881.                      grey ones.  We would gladly use the grey one
  882.                      also (or instead), but the BIOS does not read
  883.                      them when used in combination with the Alt key.
  884.  
  885.  
  886.           As operations are performed, and results displayed, QCalc
  887.      simulates a physical calculator by retaining a display of the
  888.      last 5 entries or results, ie a tape.
  889.  
  890.          [Esc], [Alt-Q]  Abortive type exit - nothing returned
  891.          [Alt-R]         Alt-R, for RETURN, closes the calculator window
  892.                          and returns to your application, returning
  893.                          the last result shown on the calculator.
  894.          [Alt-E], <E>    E or Alt-E is for Clear Entry. 
  895.                          Clears the number being entered or already        
  896.                          entered.
  897.          [Alt-C], <C>    C or Alt-C is Clear All
  898.                          Clears the entry and history by scrolling
  899.                          the tape to clear.
  900.  
  901.          [Alt-D]         Selects Decimal as the operating base.  This
  902.                          is the default when first called.  Should you
  903.                          switch to Fixed Point, QCALC will remember and
  904.                          come up in that mode.
  905.          [Alt-F]         Selects Fixed Point as the operating mode.
  906.  
  907.  
  908.          BackSpace       The backspace key is  fully supported while       
  909.                          entering digits.  When  used on a result, the     
  910.                          backspace key acts as the Clear Entry key.
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                      Copyright (C) InfoSoft 1986-1989, 1990
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.           Just as in  a physical calculator,  a result  can be rolled  over
  934.      into an entry.  Example:
  935.  
  936.             4 *     ; an entry
  937.             4 =     ; 4*4 = ??
  938.             16=     ; 16 is a _result_
  939.               +     ; tapping plus turns 16 into an _entry_ !
  940.             16+
  941.  
  942.       
  943.             III       Operation Tips
  944.  
  945.           QCalc can do  any addition, multiplication, division  or subtrac-
  946.      tion as  long as the result and both operands are within the +/- 2.147
  947.      BILLION  range.   Overflowing or  underflowing this  range will  cause
  948.      numbers to wrap: ie 2.147 BILLION plus 1 = - 2.147 BILLION and 
  949.      vice-versa.
  950.  
  951.           Percentages, as in a tax calculation, are easily handled with
  952.      multiplication or division:
  953.  
  954.           Method 1 ( 2 step process):
  955.           Tax rate of 5% on 34.65
  956.  
  957.           34.65 *          ; result of addition etc turned into entry
  958.             .05            ; enter as "." + "0" + "5"
  959.               =            ; hit enter or equal
  960.            1.72            ; this is the 5% tax amount (a _result_ !)
  961.                 +          ; turn result into entry
  962.           34.65 =          ; add back in the taxable amount
  963.           36.37            ; Total amount due
  964.  
  965.           Note:  For various reasons, the 5% amount, which is actually
  966.                  1.728 is returned as 1.72 not rounded to 1.73.
  967.  
  968.  
  969.           Method 2 (1 step process):
  970.  
  971.           34.65 *          ; result of addition etc turned into entry
  972.            1.05            ; enter as "1" - "." - "0" - "5"
  973.               =            ; hit enter or equal
  974.           36.38            ; this is the 5% tax amount (a _result_ !)
  975.  
  976.           Note:  This is not only simpler and faster, it is more
  977.                  accurate!  However many, many people do not understand
  978.                  that the total amount is going to be 100% of the
  979.                  taxable amount _plus_ 5%, ie 105% or (n * 1.05).
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.                      Copyright (C) InfoSoft 1986-1989, 1990
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.           To be  able to isolate the  tax amount, as might be  needed on an
  1000.      itemized bill,  just roll over  the result into an  entry and subtract
  1001.      the subtotal.  Continuing from above, this is done like this:
  1002.  
  1003.               -            ; roll result into a entry
  1004.           34.64            ; deduct the subtotal
  1005.            1.73 =          ; the amount added to subtotal ie the tax.
  1006.  
  1007.  
  1008.  
  1009.  
  1010.             IV        Syntax
  1011.  
  1012.           The immense power  and functionality of  QCalc is invoked with  a
  1013.      mere 5 parameters that control virtually everything:
  1014.  
  1015.        Syntax:
  1016.  
  1017.        DECALRE FUNCTION  QCalc&(Row%, Col%,  Body%, Scrn%,  Button%, Speed-
  1018.      Mode%)
  1019.          ..
  1020.          ..
  1021.          ..
  1022.        RetVal& = Calc(Row, Col, Body, Scrn, Button, SpeedMode)
  1023.  
  1024.  
  1025.            C. Parameters:
  1026.  
  1027.            RetVal&  -  QCalc will return to you the last _result_ value
  1028.                        on the QCalc display.  An entry value will not
  1029.                        be returned.  That is, entering '1+1=' will return
  1030.                        2.  Simply entering 1 only, with no operation, will
  1031.                        return the result of the last operation.
  1032.  
  1033.                        This _must_ be a long integer.  
  1034.                   
  1035.            Row, Col -  Denotes the upper left row, col coordinates for
  1036.                        the calculator display.  The size of the calculator
  1037.                        display is 31 characters wide, 20  columns tall -   
  1038.                        roughly 1/3rd  of the screen.  QCalc is not only    
  1039.                        functional but it is very smart too: should you pass
  1040.                        invalid coordinates for the row/col,  it will adjust
  1041.                        them so that the calculator display does not wrap.
  1042.  
  1043.  
  1044.           Three attribute values are passed to customize the calculator
  1045.      display  specifically  to your  needs.    QCalc will  use  the correct
  1046.      display mode for  mono vs color/EGA/VGA  displays, but does no  second
  1047.      guessing on the attributes you pass.   Be sure that the attributes you
  1048.      choose are appropriate for the display present.
  1049.  
  1050.           EGA's must be in 25 row mode or QCalc simply exits gracefully.
  1051.  
  1052.                      Copyright (C) InfoSoft 1986-1989, 1990
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.           Body     -  The color to use in the calculator body.  This
  1067.                       is the predominant color used.
  1068.  
  1069.  
  1070.           Screen   -  The color to use on the 5 line calculator display.
  1071.                       Since the end user will be focusing on this, it
  1072.                       should be an easy to read color, however certain
  1073.                       attributes can replicate a LCD appearance to
  1074.                       make the display even more realistic.
  1075.  
  1076.           Button   -  This color is used a very little, only to simulate
  1077.                       button presses and the like.  Since it is used on
  1078.                       the calculator body, some very interesting effects
  1079.                       can be created using totally different background
  1080.                       colors or the same so that just the key text changes.
  1081.  
  1082.        SpeedMode   -  This allows the programmer or end user to tailor
  1083.                       a portion of the operation characteristics.  When
  1084.                       a numeric key (0-9), E or C is pressed, the          
  1085.                       appropriate display is briefly recolored with
  1086.                       the Button Color and a tone sounds.  The SpeedMode
  1087.                       parameter allows you to set the duration for the tone
  1088.                       in clock ticks (1 / 18.2 seconds (we suggest 2).
  1089.                       This time is not system dependant so it makes no
  1090.                       difference if QCALC is called on a 386 or a 8088
  1091.                       machine.  However, you may want to turn off the beep
  1092.                       tone or speed it up or slow it down - the SpeedMode
  1093.                       parameter affords you this option.
  1094.  
  1095.                       Additionally, after the beep, QCALC purges the
  1096.                       keyboard buffer of type ahead characters, which is
  1097.                       also disabled with the SpeedMode parameter.
  1098.  
  1099.                       SpeedModes 0 to 4 do not purge the type ahead buffer
  1100.                       and represent in clock ticks, how long the tone
  1101.                       should sound in the beep/button recolor operation.
  1102.                       Zero is the shortest, with the beep/recolor disabled,
  1103.                       four is the longest with  it taking about 1/2  second
  1104.                       (twice as long as a BASIC or DOS Error BEEP !).  For
  1105.                       reference, we recommend 2.
  1106.  
  1107.                       SpeedModes 5 to 9 represent the same clock tick count
  1108.                       as 0 to 4, that is, SpeedMode 5 disables the beep
  1109.                       with the difference being that SpeedMode 5 to 9 DO
  1110.                       purge the type ahead buffer.  So SpeedMode 7 provides
  1111.                       the same display effect as 2 with the difference
  1112.                       being that 7 will eat up any keys waiting in the
  1113.                       keyboard buffer.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                      Copyright (C) InfoSoft 1986-1989, 1990
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.             V.     Programming Considerations
  1132.  
  1133.           QCalc returns the last  _result_ on the display to  your program.
  1134.      This means that in a book work type program, you could pop up QCalc to
  1135.      allow the user to add up sales or paid outs, and when they leave QCalc
  1136.      via [Alt-R], QCalc will return the last result shown on the calculator
  1137.      display!  Your program  could then automagically insert that  value on
  1138.      the screen and the proper variable!
  1139.  
  1140.           If the user leaves QCalc via [Esc] or [Alt-Q], QCalc simply 'pops
  1141.      down' and does not attempt to return anything.  You can force a return
  1142.      to your program by simply  setting up a loop until QCalc DOES return a
  1143.      value.   This maybe helpful  in cases where  the calculator  covers up
  1144.      some of the entry items on the screen forcing the user to occasionally
  1145.      'pop down' to read more info.  Ex:
  1146.  
  1147.           DO UNTIL RetVal& <> 0
  1148.               RetVal& = QCalc(row, col, attrs, attrb, attrf, speed)
  1149.  
  1150.               IF RetVal& = 0             ' no return
  1151.                   LOCATE 23, 10
  1152.                   PRINT "Return Required - Press any key for calculator."
  1153.               ELSE
  1154.                   EXIT DO                ' return was okay get outta LOOP
  1155.               END IF
  1156.  
  1157.               x$=INPUT$(1)               ' get a key, any key
  1158.               LOCATE 23,10               ' cover over msg
  1159.               PRINT SPACE$(46)
  1160.           LOOP
  1161.  
  1162.           NOTE!  NOTE!  NOTE!
  1163.  
  1164.           QCalc returns a  _LONG_ integer.  These  are 32 bits and  require
  1165.      that your receiving variable must be  an _LONG_integer.  Attempting to
  1166.      assign the result to an integer _will_ result in OVERFLOW.
  1167.  
  1168.           The return  is in  decimal mode.   If  your application is  using
  1169.      fixed point numerics, simply divide the return by 100.
  1170.  
  1171.  
  1172.           Notes
  1173.           Within the same program (ie without CHAINing, RUNning or spawning
  1174.      a new module), QCalc retains the display of the last entry or result.
  1175.      Theoretically, this allows the user to pop up QCalc, add up some
  1176.      numbers, pop down to get more info from the screen and return to
  1177.      right where they were - previously entered data is _not_ lost!
  1178.  
  1179.           It is also  important to  note that second  and third and  fourth
  1180.      calls to  QCalc do _not_ have to be at  the same location for QCalc to
  1181.      pop up the same display!
  1182.  
  1183.  
  1184.                      Copyright (C) InfoSoft 1986-1989, 1990
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.           QCalc automagically engages the Num Lock key when invoked and
  1198.      retores it when exiting.   Since we are not afflicted  with one of the
  1199.      'enhanced' 10x key keyboards, we are not yet sure what this  does with
  1200.      them.  However, it  is in deference to them and  the nonspatial -kine-
  1201.      sthetic layout that no function keys are used.
  1202.  
  1203.  
  1204.           We hope you enjoy QCalc and find it's vast power and incredible
  1205.      ease of use to be of benefit in your program.  QCalc is completely
  1206.      ported to 'C' language so that should you learn 'C' or are already
  1207.      somewhat multi lingual, this invaluable tool can 'go with you' and
  1208.      your programming endeavors.
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.                      Copyright (C) InfoSoft 1986-1989, 1990
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.                                 D.    FlexMenu
  1264.                       Copyright InfoSoft 1988 - 1990, 1991
  1265.  
  1266.  
  1267.           Flexmenu is a snappy, full featured, multi purpose menu-select
  1268.      subprogram that  supports a  plethora of  features with  a minimum  of
  1269.      setup or parameters to manage.
  1270.  
  1271.          Many  of the programs we  write require easy  to use and intuitive
  1272.      menus for novices, yet navigation still needs to be flexible enough so
  1273.      as  not to  frustrate experts.   We  routinely use  FlexMenu in  these
  1274.      situations because it fits all these needs and more.
  1275.  
  1276.          Syntax:
  1277.          item = MenuChoice% (Menu$(), Trow%, LCol%, Nattr%,  Hattr%,_      
  1278.                       title$, Mark%(), XtdChc%)
  1279.  
  1280.  
  1281.           Using the list  of items in  Menu$(), Flexmenu displays a  box on
  1282.      the  screen at the location  specified by TRow,  LCol.  FlexMenu auto-
  1283.      matically  calculates the rest of  the coordinates (length and width).
  1284.      If the number of choices is  greater than 14, the box is truncated  to
  1285.      hold the first 14, with  the rest being displayed thru the  use of the
  1286.      arrow keys.  When this is the case, and selections are off the  screen
  1287.      either above or below, up and/or down arrows (ASCII 24 and 25) will be
  1288.      located on  the  right  border.   Additionally,  FlexMenu  displays  a
  1289.      relative scroll  bar along the side of the  menu, showing where in the
  1290.      list the highlighted selection resides.
  1291.  
  1292.          The  list  of choices  or  menu items  is  in the  color attribute
  1293.      specified by Nattr  (Normal ATTRibute), and  the current selection  is
  1294.      highlighted in color  HAttr.  An optional title is centered across the
  1295.      top of the box.
  1296.  
  1297.          FlexMenu will elegantly handle as many choices as you can fit into
  1298.      string space.  Theoretically,  this is 65535, but unless  your program
  1299.      has no code, there is little chance this much can be allocated.  As we
  1300.      mentioned, for appearances,  the box  is never larger  than 14  selec-
  1301.      tions.  Navigation is intuitively managed  with the arrow keys (Up and
  1302.      Down), Pg Up, Pg  Dn, Home and End - all doing  what you would expect.
  1303.      Additionally, FlexMenu responds  to a  alpha search -  press "A"  will
  1304.      locate  and go to  (but not select)  the first item  after our current
  1305.      item starting with "A" or "a".  Pressing [Enter] returns to your  code
  1306.      the index  number of the item pressed.  If we are on item 1527, 'item'
  1307.      will be set to 1527.
  1308.  
  1309.         If you prefer your FlexMenu with a background 3-D shadow, and  most
  1310.      of us do, simply place a call to BShadow ( "CALL BShadow(1)" ) before-
  1311.      hand - this makes all Boxes calls automatically shadowed.
  1312.  
  1313.          We would find FlexMenu highly useful if that was all it did but it
  1314.      does much, MUCH more:
  1315.  
  1316.                      Copyright (C) InfoSoft 1986-1989, 1990
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.           1)  Flexmenu will automatically center  the display (which we use
  1330.      almost exclusively) by  setting both TRow and  LCol to -1.   This pre-
  1331.      vents you from having to twiddle and map out where the center is.
  1332.  
  1333.  
  1334.           2) If you are performing list processing, FlexMenu will allow you
  1335.      to 'feed' a variable representing the last item selected.  That is, if
  1336.      on  the last  call to FlexMenu,  the user  selected item 127,  we  can
  1337.      initialize the  next call  to FlexMenu  to  allow that  the last  item
  1338.      selected is highlighted on the screen!   Since this is a  modification
  1339.      from the initial releases of FlexMenu,  and is more or less an  ancil-
  1340.      lary  function, this variable is passed and defined in a COMMON SHARED
  1341.      block.  If you have no need for this feature, simply do not define the
  1342.      common block.
  1343.  
  1344.           To use this feature, define a common block as follows:
  1345.  
  1346.          COMMON SHARED /FlexVars/ FlexFeed%, FlexAll$
  1347.  
  1348.           When FlexFeed is initialized  to a value within the  range of the
  1349.      menu passed, FlexMenu  will be  scrolled so that  menu selection  cor-
  1350.      responding to it is on the display.
  1351.  
  1352.           The second COMMON  variable controls a Mark  All function covered
  1353.      later.
  1354.  
  1355.           3) It responds to extended keystrokes.  If we highlight item 156,
  1356.      and press  enter, item is  set to 156.   If we press  [Alt-Q] instead,
  1357.      item is still set to  156, but the extended choice parameter  (XtdChc)
  1358.      is  set to 16  (the ASCII code for  Alt-Q).  This  allows us to manage
  1359.      multiple functions from one  menu.  For example, we might  use DIRA to
  1360.      load a string  array and FlexMenu to  display the file names  and from
  1361.      that, [Alt-D] might delete the chosen file, but [Alt-L] might list it.
  1362.      Then via a SELECT CASE statement the  desired functions can be swiftly
  1363.      carried out.
  1364.  
  1365.           To filter out unwanted extended choices, simply place the call to
  1366.      FlexMenu in a DO or WHILE loop as shown in the following example.
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                      Copyright (C) InfoSoft 1986-1989, 1990
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.          done = 0
  1396.          DO
  1397.  
  1398.           item = MenuChoice(menu$(), -1, -1, 78, 3, "Demo", Mark(), XtdChc)
  1399.  
  1400.             SELECT CASE XtdChc
  1401.                 CASE 1, 2, 3, 4
  1402.                     GOSUB MoreChoices
  1403.                 CASE 12, 14, 15
  1404.                     GOSUB SomeStuff
  1405.                 CASE 16
  1406.                     GOSUB KillFile
  1407.                 CASE 23
  1408.                     ' get another selection
  1409.                     CLS
  1410.                  item = MenuChoice(f$(), -1, -1, 78, 3, "Demo", Mark(), XC)
  1411.  
  1412.                   IF (XC <> 27) AND (Item > 0 ) THEN
  1413.                       GOSUB GoodStuff
  1414.                   END IF
  1415.                   CLS        ' clear for next loop
  1416.  
  1417.                 CASE 27                              ' Escape
  1418.                      done = 1
  1419.                      SYSTEM
  1420.  
  1421.                 CASE 18                              ' Alt - Q
  1422.                     done = 1
  1423.  
  1424.                 CASE ELSE
  1425.                     'unsupported functions
  1426.              END SELECT
  1427.  
  1428.          LOOP UNTIL done
  1429.  
  1430.  
  1431.          In this type of construction,  we limit the methods of  ending the
  1432.      program to the 2 we are prepared  to handle.  In this way, the display
  1433.      (Menu$()) can represent  either a list of  things to act upon  such as
  1434.      file  names or  a list  of actions  or a menu  itself!   Creativity in
  1435.      nesting  allows  virtually  unlimited  possibilities  -- we  have  one
  1436.      program that manages some  40,000 items and menu functions  in 5 Flex-
  1437.      Menu calls.   The  novice user  is always  interacting with  FlexMenu,
  1438.      never DOS or the engine of the program.
  1439.  
  1440.          There is even MORE!
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.                      Copyright (C) InfoSoft 1986-1989, 1990
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.           4) FlexMenu optionally  supports a "Mark Mode" or multiple select
  1462.      function.  By setting XtdChc to  non zero upon entry, you enable  mark
  1463.      mode where pressing the TAB, or SPACEBAR toggles a mark for that item.
  1464.      The number of marks  allowed is set by XtdChc, setting it to 10 allows
  1465.      10 - and  only 10  - items to  be marked; set  to 5,  only 5 would  be
  1466.      allowed and so forth.  Marked items are tagged with bracketing " " and
  1467.      " "  (ASCII 174 and  175) characters (only  on the  display!  FlexMenu
  1468.      will not alter your menu array!), and all the other features remain in
  1469.      effect - alpha search, navigation and extended keyboard selection.
  1470.  
  1471.           To accomplish this, you must pass an integer array that is of the
  1472.      same size as your main selection string array.  FlexMenu will use this
  1473.      as a set of pointers indicating which items are Marked: if elements 5,
  1474.      6, 10 and 37 are  set (non zero) upon exiting, then the  user selected
  1475.      or marked selections 5, 6, 10 and 37 from the menu.  'Item' will STILL
  1476.      return as the highlighted  or current item when  ENTER or an  extended
  1477.      key is  pressed -  it is up  to you  to use  it or not.   If  the Mark
  1478.      integer  array is not  the same size  as the string  array of choices,
  1479.      Mark Mode is disabled.    However, if mark mode is  NOT desired, enter
  1480.      FlexMenu  with XtdChc  set to  0 and/or dimension  Mark() to  a single
  1481.      element.
  1482.       
  1483.           You will recall  that the COMMON  block contains a vaiable  names
  1484.      "FlexAll$".  If defined, when the user presses the key defined  by you
  1485.      as FlexAll$,  ALL the  items in  the list  are MARKED.   This  feature
  1486.      respects  the value  of the maximum  MARKS allowed by  XtdChc, so this
  1487.      feature  is only available when all XtdChc=UBOUND(Menu$), ie all items
  1488.      in the list can  be marked.  For  example to define Alt-Q as  the Mark
  1489.      All key, 
  1490.        FlexAll$ = CHR$(0) + CHR$(16)        ' Extended key code for Alt-Q
  1491.      If/when the user preses Alt-Q all menu items will be marked.
  1492.  
  1493.  
  1494.           5) FlexMenu will  also "remember" previous marks  upon subsequent
  1495.      calls unless you REDIM the MARK array.  FlexMenu examines Mark() as it
  1496.      is setting up and treats non zero elements as marks.  That is, upon
  1497.      initializing it does  not assume  that it  is the first  time.   Using
  1498.      this, you can "suggest" selections by setting the corresponding Mark()
  1499.      element before  calling FlexMenu -  the user  can of course  toggle it
  1500.      off, but in cyclical  applications, the user need not  remark previous
  1501.      selections.
  1502.  
  1503.  
  1504.           We use  FlexMenu almost exclusively  in our menu  driven applica-
  1505.      tions,  since  it is  powerful, fast,  relatively  small and  has many
  1506.      features and have found it to meet most every need.   
  1507.  
  1508.  
  1509.          NOTE:  FlexMenu  requires the  QPrint,  Scroll,  QPrintV, Painter,
  1510.      StrLen and Boxes object modules.
  1511.  
  1512.  
  1513.  
  1514.                      Copyright (C) InfoSoft 1986-1989, 1990
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.                                     E.  StatLine
  1528.                     Copyright (C) InfoSoft 1988 - 1990, 1991
  1529.  
  1530.          I. Overview
  1531.  
  1532.           StatLin is the  name of the  object file containing several  rou-
  1533.      tines or primitives  that aid you  in displaying and/or controlling  a
  1534.      one or  two row status line.   Collectively, we will refer  to them as
  1535.      StatLine.
  1536.  
  1537.          These routines are:
  1538.  
  1539.          CLX       -  Clear the screen except for the status line area.
  1540.          SetBline  -  Set the bottom line of the non status line area of
  1541.                       the screen.  Similar in function to the BASIC WINDOW
  1542.                       statment.
  1543.          PrintStatL - Prints all or part of  an array designated for the   
  1544.                       status line.
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.          II.   Operation
  1553.  
  1554.           The default bottom line of a  screen using StatLine procedures is
  1555.      row 23, or a 2 row status line as used in  the demo.  You can set this
  1556.      to more or less depending on your needs, thus allowing you to use even
  1557.      5 lines for the status area or even simulating a split screen effect.
  1558.  
  1559.           If you use more than 1 or 2 rows for the status line however, you
  1560.      will need to maintain those above 24  as PrintStatL will only print to
  1561.      line 24 and/or 25).  Beyond that limitation, these routines allow for
  1562.      printing and updating a status line, and clearing the non status line
  1563.      portion of the screen.
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.                      Copyright (C) InfoSoft 1986-1989, 1990
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.          III. Functions
  1595.  
  1596.  
  1597.          Name: SetBVLine            Type: SUB               Level: ASM
  1598.          Syntax: CALL SetBVLine(x)
  1599.  
  1600.           As mentioned, the default bottom line of a screen using StatLine
  1601.      procedures is row 23, or a 2 row status line as used in the demo. If
  1602.      you wish to reserve more or less area than that, SetBVLine will allow
  1603.      you to  Set the Bottom  Video Line to  be respected by  PrintStatL and
  1604.      CLX.
  1605.  
  1606.           Note that if  you set it  to 23,  a call to  CLX will ONLY  clear
  1607.      lines 1  to 23, saving the bottom two  status lines and preventing you
  1608.      from having to redraw them.  However,  CLS will still clear the entire
  1609.      screen.
  1610.  
  1611.  
  1612.            
  1613.  
  1614.  
  1615.          Name: CLX                 Type: SUB                Level: ASM
  1616.          Syntax: CALL CLX
  1617.          This may also be called or invoked as ClrScrn
  1618.  
  1619.          This simply  clears the  non status  line portion  of the  screen.
  1620.      Where CLS would clear  all 25 rows of video, CLX  respects the default
  1621.      bottom video  line of  22 or whatever  you have  set it to  using Set-
  1622.      BVLine.
  1623.  
  1624.           Like BASIC's native CLS statement, this also relocates the cursor
  1625.      location to 1,1 by performing a call to the actual BASIC RTL (Run Time
  1626.      Library) so that not only the cursor is physically relocated, but the
  1627.      internal  cursor  location variables  held  by  the QB  RTL  are reset
  1628.      allowing CSRLIN and POS(0) as well as PRINT  to act as expected.  That
  1629.      is, an explicit LOCATE 1,1  is not needed to complete  the CLX/ClrScrn
  1630.      function.
  1631.  
  1632.  
  1633.  
  1634.          Name: PrintStatL          Type: SUB                     Level: ASM
  1635.          Syntax: CALL PrintStatL(StatMsg(1), Action, Attr)
  1636.  
  1637.  
  1638.           This prints all or part of a  2 element fixed length 80 character
  1639.      string array to  the status line area  of the screen in  the designted
  1640.      color.
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.                      Copyright (C) InfoSoft 1986-1989, 1990
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.          1. To pass a fixed length string array to a CALLed ASM sub, you
  1660.             must hide it in a TYPE structure  by setting up a user defined 
  1661.             TYPE that is simply a single 80 character string.
  1662.             Ex:
  1663.  
  1664.             TYPE struct                      ' tell QB what it looks like
  1665.                fls AS STRING * 80
  1666.             END TYPE
  1667.  
  1668.             DIM StatMsg(2) AS struct         ' order one
  1669.  
  1670.  
  1671.          2. Also to pass a TYPE structure  to an ASM routine, you must     
  1672.             DECLARE it using the keyword ANY.  So the DECALRE for
  1673.             PrintStatL would be:
  1674.  
  1675.  
  1676.             DECALRE SUB PrtSL(MsgArry AS ANY, Action%, Attr%)
  1677.  
  1678.          3. At this point, we may fill  the array with messages.  Feel free
  1679.             to use LSET or RSET with the array to justify strings. Example:
  1680.           StatMsg(1).fls = "  Time: " + TIME$ + "   Temp: "+ degree$ + msg$
  1681.           StatMsg(2).fls = "  Code: " + Information$
  1682.  
  1683.          4. Finally invoke it with the desired action code and attribute:
  1684.             CALL PrtSL(StatMsg(1), 0, Attr)
  1685.  
  1686.           ActionCode tells PrtSl what action to perform:
  1687.           0 = Print/Update both lines 24 and 25
  1688.           1 = Print/update line 24 only
  1689.           2 = Print/update line 25 only
  1690.  
  1691.          In more  sophisticated applications,  you can  define more  than 2
  1692.      elements for the message  array and selectively update  higher offsets
  1693.      in the  array.   For instance,  if your  program has  5 main  function
  1694.      levels, you might  need 5 different status  line displays.  Using  a 2
  1695.      line display means we need 10 elements so,
  1696.  
  1697.             DIM StatMsg(10) AS struct         ' set up 5 status line SETS
  1698.  
  1699.           When we are working on the Main or top level we invoke elements
  1700.      1 and 2 to print to lines 24 and 25 as normal (above).  For subsequent
  1701.      levels we  pass the element to  be mapped or  printed to line  24, the
  1702.      second activity level would be:
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.                      Copyright (C) InfoSoft 1986-1989, 1990
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.           CALL PrtSL(StatMsg(3), 0, Attr)
  1727.          ' element 3 goes to 24, 4 to line 25
  1728.  
  1729.  
  1730.          ' level 3:
  1731.  
  1732.             CALL PrtSL(StatMsg(5), 0, Attr)
  1733.  
  1734.          ' and so on to level 5:
  1735.             CALL PrtSL(StatMsg(9), 0, Attr)
  1736.  
  1737.  
  1738.           Of course, your  use of OPTION BASE 0 means you subtract one from
  1739.      the element passed.
  1740.  
  1741.           Notes:
  1742.           Being a fixed length string, a very large number of status line
  1743.      messages can be stored in your fixed length sting array, but be sure
  1744.      to use the /ah switch if the array is to be more than 64k.  Also,
  1745.      large fixed length string arrays should ALWAYS be even multiples of 2.
  1746.      This is so  that if and when they span a segment boundary, the segment
  1747.      boundary will break at the  start of an element and NOT  in the middle
  1748.      of a string or structure. 
  1749.  
  1750.  
  1751.  
  1752.           QB inititializes a fixed length string to NULLs, NOT SPACES, so
  1753.      displaying a message array that  you have not modified, may result  in
  1754.      unexpected results.
  1755.  
  1756.           PrintStatL expects a  2 line status area, so to use only line 25,
  1757.      your message array would still have to be 2 elements per  "level", but
  1758.      every other one  would be blank  or NULL.   MsgArry(1) always maps  to
  1759.      line 24, as does 3, 5, 7, 9 etc.  These would be blank, but 2, 4, 6, 8
  1760.      etc would  be filled for mapping to line 25  when you want to use only
  1761.      line 25.  Note that SetBVLine has no effect on PrintStatL only on CLX.
  1762.  
  1763.          PrintStatL expects the message  array to be a 80  character string
  1764.      array - if  you dimension it to  a smaller number the  memory contents
  1765.      immediately following the arry will be printed.  Ex: if you DIM it to
  1766.      STRING * 60 (rather than 80), line 24 would display the first element
  1767.      PLUS the first 20 characters of the second, and the bottom line would
  1768.      display the next 40 characters of the second element PLUS what ever
  1769.      garbage is in the next 40 bytes of memory.
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.                      Copyright (C) InfoSoft 1986-1989, 1990
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.                                 F.    DialogBox
  1792.                        Copyright (C) InfoSoft 1989 - 1990, 1991
  1793.  
  1794.  
  1795.  
  1796.           I.    Overview
  1797.  
  1798.           If you've ever  carefully looked  at the code  for most  finished
  1799.      programs of any  size, you can often  be amazed at the amount  of code
  1800.      that is  dedicated simply  to validating user  I/O.  Be  it precluding
  1801.      invalid filenames, verfying an input character or reacting to an error
  1802.      situation, vast  portions  of code  (and  naturally, coding  time)  in
  1803.      'bullet proof' programs end up dedicated to this.
  1804.  
  1805.  
  1806.  
  1807.           Naturally if you use one menuing method and one or two user I/O
  1808.      routines and CALL  or GOSUB to them,  your program size could  be con-
  1809.      siderably reduced.  That is what we did on one application: all
  1810.      select-from-menu  inputs were  replaced by FlexMenu(qv),  all extended
  1811.      string input was replaced by MFed, and all program-to-user messages
  1812.      (like "Overwrite File?" "File Does not exist!" etc) with the likes
  1813.      of PGetCh, GetCh  and WINDOWS  were replaced  by Boxes.   With  little
  1814.      other code structure changes, the program shrunk 17% !
  1815.  
  1816.  
  1817.  
  1818.           DialogBox is an SAA style input box designed loosely after the
  1819.      ubiquitous dialog  boxes found in QB, QBX, TC and  QC as well as other
  1820.      integerated applications (MICROSOFT WINDOWS...).  DialogBox allows you
  1821.      a  simple,  compact, fast,  all-pupose  method of  communicating error
  1822.      conditions and/or  choices to  the end user,  and get a  delimited re-
  1823.      sponse from them.
  1824.  
  1825.  
  1826.  
  1827.           The functionality of DialogBox comes from a minimum of parameters
  1828.      needing to be passed.  You pass only a few strings, and the routine
  1829.      automatically determines the size of the box.
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.                      Copyright (C) InfoSoft 1986-1989, 1990
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.          II   Parameters
  1858.  
  1859.  
  1860.              Name: DialogBox                Type: FUNCTION
  1861.          Syntax: ret$ = DialogBox$(msg$, prompt$, okay$)
  1862.  
  1863.  
  1864.          Msg$ -    Typically, this would be used to explain or describe  a 
  1865.                    problem or error, or to pose the premise of a question
  1866.                    you wish to ask.  Example:
  1867.                    "File Not Found"
  1868.                    "Error writing to disk"
  1869.                    "Printer not online"
  1870.                    "Delete all files"
  1871.  
  1872.  
  1873.          Prompt$ - This might typically explain the list of possible
  1874.                    actions or choices or expand on the Msg$ displayed.     
  1875.                    Examples:
  1876.                    "Abort or Retry?"
  1877.                    "Swap Disks, Retry"
  1878.                    "Fail or Retry"
  1879.                    "Yes, No or Cancel"
  1880.  
  1881.  
  1882.                    
  1883.          Okay$ -   Tells DialogBox what input is ok.  This list is
  1884.                    displayed in the DialogBox on the line below prompt$.
  1885.                    Additionally, if Okay$ is NULL ( "" ), then DialogBox
  1886.                    will accept any key press as an act of acknowledgment by
  1887.                    the user and "< OK >" is displayed where the OK list
  1888.                    normally would be.  This list must be in upper case see
  1889.                    GetCh.
  1890.  
  1891.  
  1892.          ret$  -   Returns to your calling program the upper case character
  1893.                    pressed from the okay list that allowed the user to exit
  1894.                    DialogBox.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.                      Copyright (C) InfoSoft 1986-1989, 1990
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.          Syntax example:
  1924.  
  1925.          msg$ = "Delete marked Files?"
  1926.          prompt$ = "Yes, No or Cancel"
  1927.          okay$ = "YNC"
  1928.          ret$ = " "
  1929.  
  1930.  
  1931.          OutPut:        (this may be distorted depending on your printer)
  1932.  
  1933.                                                     
  1934.                                                     
  1935.                              Delete Marked Files?   
  1936.                               Yes, No or Cancel     
  1937.                                                     
  1938.                                                     
  1939.                                 <Y>  <N>  <C>       
  1940.                                                     
  1941.  
  1942.          The entire  box is  cenetered horizontally  and vertically  on the
  1943.      display,  all text  is centered  within the  box, a single  line frame
  1944.      border  is used  and the  color attribute  is black  on white  reverse
  1945.      video.   As  mentioned, the  left and  right borders  of  the box  are
  1946.      calculated internally to  DialogBox so  you need not  mess with  loca-
  1947.      tions.
  1948.  
  1949.          DialogBox does NOT do any screen saving and it does not  check for
  1950.      string length  errors: a msg$ length  of more than 78  characters will
  1951.      surely cause unexpected and/or unknown results.
  1952.  
  1953.          The defaults used in DialogBox (location, color etc) are  designed
  1954.      to be as SAA-like as possible, to make invoking it as easy as possible
  1955.      and as always, lightening fast.   However, the defaults can be changed
  1956.      either for current or subsequent calls.
  1957.  
  1958.          In the example,  you will  note that DialogBox  parses the  passed
  1959.      okay$ and  displays them individually within brackets.  If the list of
  1960.      okay responses is  more than 5 however, or both the message and prompt
  1961.      are abnormally  short, it  will simply  list them:   QWERTY  is simply
  1962.      centered.
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                      Copyright (C) InfoSoft 1986-1989, 1990
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.          III   Altering DialogBox defaults
  1991.  
  1992.           As is, the  DialogBox defaults eliminate  many decisions such  as
  1993.      colors to use depending on the monitor type, where to locate it and so
  1994.      forth, and  provide a  SAA appearance  to the  program.   However some
  1995.      people are  going to  just die  if they  can't use  colors with  it or
  1996.      locate it somewhere else (in fact, re-locating the box may be required
  1997.      in  some cases where something relevant to the message gets covered up
  1998.      by it).
  1999.  
  2000.          So, should you want to change any of these, we have devised a sub
  2001.      program to set user defined defaults:
  2002.  
  2003.  
  2004.  
  2005.              Name: DBoxSetUDef              Type: SUB
  2006.          CALL DBoxSetUDef(TRow, LCol, Frame, BAttr)
  2007.  
  2008.          TRow   -  The top row for DialogBox
  2009.          LCol   -  The left column for the location
  2010.          Frame  -  The style of frame to  be used (see BOXES for a complete
  2011.                    list)
  2012.          BAttr  -  The new default color to use
  2013.  
  2014.  
  2015.           Once called, DBoxSetUDef  sets a flag to instruct  DialogBox that
  2016.      user defined parameters  are in effect and  to use them.   These para-
  2017.      meters, in fact  become the new defaults until you reset them or clear
  2018.      them.  This allows you to position and color the box any way you like.
  2019.       Note that you only need to set the Top Row and Left Column: DialogBox
  2020.      will  still calculate  the bottom  and right  box frames based  on the
  2021.      length of the strings.   You  cannot make the box bigger and locations
  2022.      are NOT verified:  Setting the top  row to 52  will have unwanted  re-
  2023.      sults.  Note that using DBoxSetUDef means that ALL  the parameters are
  2024.      changed.
  2025.  
  2026.  
  2027.  
  2028.  
  2029.              Name: DBoxClrUDef              Type: SUB
  2030.          CALL DBoxClrUDef
  2031.  
  2032.          This merely clears any user defined parameters from DialogBox and
  2033.          allows it to once again execute with default parameters.
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.                      Copyright (C) InfoSoft 1986-1989, 1990
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.              Name: DBoxSound                Type: SUB
  2056.          CALL DBoxSound(SFlag, Frequency, Duration)
  2057.  
  2058.          Since I often find  myself sounding the speaker just as I pop up a
  2059.      DialogBox, we  have gone  ahead and  built in  sound capability.   The
  2060.      default tone for this  is the equivalent of using  GLib's SpeakerSound
  2061.      routine:   CALL SpkrSnd(1200, 1)
  2062.  
  2063.          The  default for the sound  is ON with  a frequency of  1200 and a
  2064.      duration of 1.  To alter any of  these, simply use DBoxSound.  Setting
  2065.      SFlag to 0  turns the sound off, 1 turns it  on.  To alter the default
  2066.      tone, call DBoxSound with SFlag set to  one and frequency and duration
  2067.      set to the desired values.
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.          IV  Usage
  2075.  
  2076.  
  2077.            One  way  we have  used this  was to  have all  possible program
  2078.      messages,  prompts etc stored in an Fixed length string array and when
  2079.      needed, we  simply called  a DBox handler  with an  ActionCode.   This
  2080.      handler then  copied the strings to  a normal array,  saved the screen
  2081.      image,  called DialogBox, erased  the temp array,  restored the screen
  2082.      and returned the selected character to the main program.
  2083.  
  2084.            Alternatively, a larger program that could not spare the memory,
  2085.      left all such messages in a random file.  The box handler then fetched
  2086.      the necessary text from the file (keyed on the ActionCode) into simple
  2087.      strings, called DialogBox and then returned the input.  Using such
  2088.      techinques, the main program need only determine error conditions, and
  2089.      act on reponses  - all the I/O  with the user  is relagated to a  sub-
  2090.      program.
  2091.  
  2092.  
  2093.           There is a little less flash and dazzle to DialogBox than emulat-
  2094.      ing  the same with  MFed and WINDOWS  but in  very large applications,
  2095.      where code space or development time is critical, rather than spending
  2096.      time with setting up actions and such DialogBox can provide a uniform,
  2097.      straight forward very fast approach to simple prompted user I/O.
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.                      Copyright (C) InfoSoft 1986-1989, 1990
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.